<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>IupGLSubCanvas</title>

<link rel="stylesheet" type="text/css" href="../../style.css">
<style type="text/css">
.style1 {
	font-size: medium;
	letter-spacing: normal;
	background-color: #FFFFFF;
}
.style2 {
	background-color: #FFFFFF;
}
.style3 {
	font-size: large;
}
.auto-style2 {
	background-color: #CEE7FF;
}
</style>
</head>
<body>
<div id="navigation">
  <ul>
    <li><a href="#Creation">Creation</a></li>
    <li><a href="#Attributes">Attributes</a></li>
    <li><a href="#Callbacks">Callbacks</a></li>
    <li><a href="#Notes">Notes</a></li>
    <li><a href="#Examples">Examples</a></li>
    <li><a href="#SeeAlso">See Also</a></li>
  </ul>
</div>

<h2>IupGLSubCanvas<span class="style3"> (since 3.11)</span></h2>
<p>Creates an embedded OpenGL sub-canvas. It exists only inside an
<a href="iupglcanvasbox.html">IupGLCanvasBox</a>.</p>
<p>This is an additional control that depends on the OpenGL library. It is included 
in the 
<a href="../iupglcontrols.html">IupGLControls</a> library.</p>
<p>It is a void element that does not map to a native canvas. It mimics an
<strong>IupCanvas</strong> with several attributes and callbacks in common, but 
everything is done inside a region of the <strong>IupGLCanvasBox</strong>.</p>
<p>The element does not to be a direct child of the <strong>IupGLCanvasBox</strong>. 
It can be place inside void containers like <strong>IupHbox</strong>, <strong>
IupVbox</strong>, <strong>IupGridBox</strong> and so on.</p>
<p>This control is used as the base control for all visual elements of the
<strong>IupGLControls</strong> library.</p>
<h3><a name="Creation">Creation</a></h3>
<div>
  <pre>Ihandle* IupGLSubCanvas(void); [in C]
iup.glsubcanvas{} -&gt; (<strong>elem</strong>: ihandle) [in Lua]
glsubcanvas() [in LED]</pre>
</div>
  <p>
  <u>Returns:</u> the identifier of the 
  created element, or NULL if an error occurs.</p>

<h3><a name="Attributes">Attributes</a></h3>


  <p><b>ACTIVE</b>:
  disables mouse interaction and highlight feedback. Also for some controls it 
  will affect its appearance to greyed version. Possible values:
  &quot;YES, 
  &quot;NO&quot;. 
  Default:
  &quot;YES&quot;.</p>



<p><strong>BGCOLOR</strong>: background color used in derived controls. Can have 
an alpha component. Default: NULL.</p>
<p><strong>BORDERCOLOR</strong>: color used for borders in derived controls. Can 
have an alpha component. Default: &quot;50 150 255&quot;.</p>
<p><strong>BORDERWIDTH</strong>: line width used for borders in derived 
controls. Default: &quot;1&quot;. Any borders can be disabled by simply setting 
this value to 0.</p>

<p><a href="../attrib/iup_cursor.html">CURSOR</a> (<font size="3">non inheritable</font>):
    Defines a cursor for the sub-canvas.</p>

  
<p>
<a href="../attrib/iup_font.html">FONT</a>: Uses the FTGL library to render 
text in OpenGL using the Freetype library. Depends on locating a font file that matches the font attribute. See
<a href="#Notes">Notes</a> bellow. The default font typeface is changed to 
Helvetica to avoid system fonts that are not well processed by FreeType.</p>
<p><strong>HIGHLIGHT</strong> (<font size="3">non inheritable</font>):  
flag indicating that the control is highlighted. Dynamically updated during 
mouse move.</p>
<p><strong>HLCOLOR</strong>: color used to indicate a highlight state in derived 
controls. Can have an alpha component. Default: &quot;200 225 245&quot;.</p>
<p><strong>PSCOLOR</strong>: color used to indicate a press state in derived 
controls. Can have an alpha component. Default: &quot;150 200 235&quot;.</p>
<p><strong>PRESSED</strong> (<font size="3">non inheritable</font>):  
flag indicating that the control is pressed with button1. Dynamically updated 
during button press.</p>
<p><strong>REDRAWALL</strong> (<font size="3">non inheritable</font>):  
flag to control the redraw update during a change of state like highlight or 
pressed. If &quot;No&quot; only the element is redrawn, else all the <strong>
IupGLCanvasBox</strong> is redrawn. It will work only if the control is fully 
opaque. Default: &quot;Yes&quot;.</p>
<p><strong>REDRAWFRONT</strong> (<font size="3">non inheritable, write-only</font>): 
redraw only the control on the front buffer. It will work only if the control is 
fully opaque. </p>
<p><strong>UNDERLINE</strong> (<font size="3">non inheritable</font>):  
flag indicating that the control text should be redrawn with an underline. Since 
FTGL does not supports underline, the drawing of the text will manually draw a 
line under the text.</p>
<p>
    <a href="../attrib/iup_wid.html">WID</a> (<font size="3">non inheritable</font>): 
returns the same value as the <strong>IupGLCanvasBox</strong> where the element 
is inside.</p>
<p>
    <a href="../attrib/iup_zorder.html">ZORDER</a> (<font size="3">non inheritable, 
write-only</font>): change the order of the control inside its parent.</p>

<blockquote>
  
  <hr>
</blockquote>

<p>
&nbsp;<a href="../attrib/iup_screenposition.html">SCREENPOSITION</a>, 
<a href="../attrib/iup_position.html">
POSITION</a>, <a href="../attrib/iup_minsize.html">
MINSIZE</a>, <a href="../attrib/iup_maxsize.html">
MAXSIZE</a>,
    <a href="../attrib/iup_tip.html">TIP</a>, <a href="../attrib/iup_size.html">SIZE</a>, 
<a href="../attrib/iup_rastersize.html">RASTERSIZE</a>,
    <a href="../attrib/iup_visible.html">VISIBLE</a>: 
also accepted.</p>

<h3><a name="Callbacks">Callbacks</a></h3>


<p><strong>GL_ACTION</strong>: Action generated when the 
sub-canvas needs to be redrawn. The transformation matrix is already set to the 
subcanvas rectangular region. Also, do not call <strong>IupGLMakeCurrent</strong> 
nor <strong>IupGLSwapBuffers</strong>, the <strong>IupCanvasBox</strong> 
management will take care of that.</p>

  
    
<pre>int function(Ihandle *<strong>ih</strong>); [in C]<br><strong>elem</strong>:gl_action() -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.</p>

  
  
<p><strong>GL_BUTTON_CB</strong>:
  Action generated when any mouse button is 
  pressed or released. Same parameters as <a href="../call/iup_button_cb.html">BUTTON_CB</a>. 
If IUP_CONTINUE is returned the application callback is called even the user 
clicked on the sub-canvas.</p>
<p><strong>GL_ENTERWINDOW_CB</strong>: Action generated when the mouse enters 
the element. Same parameters as 
<a href="../call/iup_enterwindow_cb.html">ENTERWINDOW_CB</a>.</p>
<p><strong>GL_LEAVEWINDOW_CB</strong>: Action generated when the mouse leaves 
the element. Same parameters as
  <a href="../call/iup_leavewindow_cb.html">LEAVEWINDOW_CB</a>.</p>

  

  
<p><strong>GL_MOTION_CB</strong>:
  Action generated when the mouse is moved. Same parameters as <a href="../call/iup_motion_cb.html">MOTION_CB</a>.&nbsp; 
If IUP_CONTINUE is returned the application callback is called even the user 
moved the cursor on the sub-canvas.</p>

  
<p><strong>GL_WHEEL_CB</strong>: Action generated when the mouse wheel is 
  rotated. Same parameters as <a href="../call/iup_wheel_cb.html">WHEEL_CB</a>.&nbsp; 
If IUP_CONTINUE is returned the application callback is called even the user 
clicked on the sub-canvas.</p>

  

  
<blockquote>
  
  <hr>
</blockquote>

<p> 
<a href="../call/iup_map_cb.html">MAP_CB</a>, 
<a href="../call/iup_unmap_cb.html">UNMAP_CB</a>,
<a href="../call/iup_destroy_cb.html">DESTROY_CB</a>:  common callbacks are 
supported.</p>

  

<h3>Utilities (since 3.20)</h3>
<p>Since there is no high quality text rendering in OpenGL we use FTGL and 
Freetype to load fonts and render using OpenGL. So we also export the same 
function used internally so the applications can have the same functionality for 
other purposes, among with other utilities for text and images.</p>
<pre>void IupGLDrawText(Ihandle* <strong>ih</strong>, const char* <strong>str</strong>, int <strong>len</strong>, int <strong>x</strong>, int <strong>y</strong>); [in C]
iup.GLDraw<span class="auto-style2">Text(</span><strong>ih</strong>: ihandle<span class="auto-style2"><strong>, str</strong>: string, <strong>x</strong>, <strong>y</strong>: number)</span> [in Lua]
<strong>ih</strong>:GLDrawText(<span class="auto-style2"><strong>str</strong>: string, <strong>x</strong>, <strong>y</strong>: number</span>) [in Lua]</pre>
<p>Draws a text in the given position using the current
<a href="../attrib/iup_font.html">FONT</a>. The size of the string is used only 
in C. Can be -1 so <strong>strlen</strong> is used internally. The coordinates 
are relative the top-left corner of the text. <strong>ATTENTION</strong>: 
Different from the <strong>IupDrawText</strong> function, the color of the text 
uses the current color set in the OpenGL context.</p>
<pre>void IupGLDrawImage(Ihandle* <strong>ih</strong>, const char* <strong>name</strong>, int <strong>x</strong>, int <strong>y</strong>, int <strong>active</strong>); [in C]
iup.GLDraw<span class="auto-style2">Image(</span><strong>ih</strong>: ihandle<span class="auto-style2"><strong>, name</strong>: string or <strong>image</strong>: ihandle, <strong>x</strong>, <strong>y, active</strong>: number)</span> [in Lua]
<strong>ih</strong>:GLDrawImage(<strong>name</strong><span class="auto-style2">: string or <strong>image</strong>: ihandle, <strong>x</strong>, <strong>y, active</strong>: number</span>) [in Lua]</pre>
<p>Draws an image given its name. The coordinates are relative the top-left 
corner of the image. The image name follows the same behavior as the IMAGE 
attribute used by many controls.
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.8px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 1; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">
Use<span class="Apple-converted-space">&nbsp;</span></span><a href="../func/iupsethandle.html" style="font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.8px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 1; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">IupSetHandle</a><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.8px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 1; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);"><span class="Apple-converted-space">&nbsp;</span>or<span class="Apple-converted-space">&nbsp;</span></span><a href="../func/iupsetattributehandle.html" style="font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.8px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 1; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">IupSetAttributeHandle</a><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.8px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 1; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);"><span class="Apple-converted-space">&nbsp;</span>to 
associate an image to a name. See also<span class="Apple-converted-space">&nbsp;</span></span><a href="../elem/iupimage.html" style="font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.8px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 1; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">IupImage</a><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.8px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 1; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">.<span class="Apple-converted-space">&nbsp;In 
Lua, the name parameter can be the actual image handle. When active 
parameter is 0, it will draw the same image in inactive state.</span></span></p>
<pre>void IupGLDrawGetTextSize(Ihandle* <strong>ih</strong>, const char* <strong>str</strong>, int *<strong>w</strong>, int *<strong>h</strong>); [in C]
iup.GLDrawGetTextSize<span class="auto-style2">(</span><strong>ih</strong>: ihandle<span class="auto-style2">, <strong>str</strong>: string) -&gt; <strong>w</strong>, <strong>h</strong>: number</span> [in Lua]
<strong>ih</strong>:GLDrawGetTextSize(<span class="auto-style2"><strong>str</strong>: string</span>)<span class="auto-style2"> -&gt; <strong>w</strong>, <strong>h</strong>: number</span> [in Lua]</pre>
<p>Returns the given text size using the current
<a href="../attrib/iup_font.html">FONT</a>.&nbsp; In C unwanted values can be 
NULL.</p>
<pre>void IupGLDrawGetImageInfo(const char* <strong>name</strong>, int *<strong>w</strong>, int *<strong>h</strong>, int *<strong>bpp</strong>); [in C]
iup.GLDrawGetImageInfo<span class="auto-style2">(<strong>name</strong>: string) -&gt; <strong>w</strong>, <strong>h, bpp</strong>: number</span> [in Lua]
<strong>ih</strong>:GLDrawGetImageInfo(<strong>name</strong><span class="auto-style2">: string</span>)<span class="auto-style2"> -&gt; <strong>w</strong>, <strong>h, bpp</strong>: number</span> [in Lua]</pre>
<p>Returns the given image size and bits per pixel. bpp can be 8, 24 or 32.&nbsp; 
In C unwanted values can be NULL.</p>

  

<h3><a name="Notes">Notes</a></h3>


<p>
  FTGL and Freetype are<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.799999237060547px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">
  third party libraries not developed at Tecgraf. But their licenses are 
  also free and have the same freedom as the<span class="Apple-converted-space">&nbsp;</span></span><a href="../copyright.html" style="font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.799999237060547px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">Tecgraf 
  Library License</a><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.799999237060547px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">. 
  You can read the license and copyright in the file<span class="Apple-converted-space">s&nbsp;</span></span><a href="../ftgl.txt" style="font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.799999237060547px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">ftgl.txt</a><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.799999237060547px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);"> 
  and <a href="../freetype.txt">freetype.txt</a>. 
  FTGL is copyright to Henry Maddocks.</span></p>
<p>
  <span class="style1">IUP uses the same FTGL library i<span class="style2">ncluded 
  in</span> the CD library.
  <span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.799999237060547px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">
  Currently CD is using the FTGL version 2.1.3-rc5 with modifications.</span></span></p>
<p>
  <span class="style1">To locate font files we use several strategies.</span></p>
  <blockquote>
<ol>
	<li>
	search for the font in the system. In Windows use the 
	Registry to locate the font, in UNIX use the FontConfig library;
	</li>
	<li>
	use the type face as a file title, compose with the font path to get a 
	filename (assume style already in the typeface);</li>
		<li>
		try some pre-defined names, and use the style to compose the filename;</li>
	<li>
		use the typeface directly as the file name;</li>
</ol>
	  <p>It will search for TrueType (*.ttf) and OpenType (*.otf) font files. It 
	  will search in the current directory; in the path returned by the 
	  FREETYPEFONTS_DIR environment variable or from the FREETYPEFONTS_DIR 
	  global attribute; and in Windows on the Fonts folder.</p>
</blockquote>
<p>
  FTGL fonts are cached internally to optimal use of multiple fonts in the same
  <strong>IupGLCanvasBox</strong>.</p>
<p>
  We use OpenGL textures to draw images, so the image width and height MUST be a 
  power of two if OpenGL version is 1.x, modern OpenGL does not have this 
  limitation. </p>
<h3><a name="SeeAlso">See Also</a></h3>

<p>
<a href="../elem/iupcanvas.html">IupCanvas</a></p>

</body>

</html>